/**
 * @file imagecanvas.h
 * @brief 图像画布组件头文件
 *
 * 定义图像显示、交互绘制和蒙版管理的核心类
 * 这个类是图像修复系统的可视化核心
 */

#ifndef IMAGECANVAS_H
#define IMAGECANVAS_H

#include <QWidget>          // Qt窗口部件基类
#include <QPixmap>          // Qt图像显示类
#include <QPainter>         // Qt绘图工具
#include <QMouseEvent>      // 鼠标事件处理
#include <opencv2/opencv.hpp> // OpenCV图像处理库

/**
 * @brief 图像画布类
 *
 * 负责图像的显示和用户交互，主要功能包括：
 * - 图像文件的加载、显示和缩放
 * - 鼠标交互绘制修复蒙版
 * - 多种绘制工具支持
 * - 修复结果的显示
 *
 * 设计特点：
 * - 双图像存储：同时维护Qt格式（显示）和OpenCV格式（处理）
 * - 实时坐标转换：处理屏幕坐标与图像坐标的映射
 * - 信号槽机制：与其他组件通信
 */
class ImageCanvas : public QWidget
{
    Q_OBJECT  // Qt宏，启用信号槽和元对象系统

public:
    // 工具类型枚举
    enum Tool {
        Pen,        // 画笔工具 - 自由绘制
        Rectangle,  // 矩形工具 - 绘制矩形区域（待实现）
        Eraser      // 橡皮擦工具 - 擦除已绘制区域
    };

    explicit ImageCanvas(QWidget *parent = nullptr);

    // ==================== 图像操作接口 ====================
    bool loadImage(const QString &filePath);        // 加载图像文件
    bool saveImage(const QString &filePath);        // 保存图像文件（待实现）
    void clearMask();                               // 清除所有蒙版
    void showResult(const cv::Mat &result);         // 显示修复结果
    const cv::Mat& getOriginalImage() const { return originalImage; } // 获取原始图像

    // ==================== 蒙版操作接口 ====================
    cv::Mat getMask() const { return maskImage.clone(); } // 获取当前蒙版
    void setDrawMode(bool enabled);                 // 启用/禁用绘制模式
    void setBrushSize(int size) { brushSize = size; update(); } // 设置画笔大小

    // ==================== 工具操作接口 ====================
    void setCurrentTool(Tool tool);                 // 设置当前绘制工具

protected:
    // 重写的事件处理函数
    void wheelEvent(QWheelEvent *event) override;   // 鼠标滚轮事件（缩放）

public slots:
    // 公开的槽函数 - 供其他组件调用
    void zoomIn();      // 放大图像
    void zoomOut();     // 缩小图像
    void resetZoom();   // 重置缩放比例

signals:
    // 信号定义 - 用于通知其他组件状态变化
    void imageLoaded(bool success);             // 图像加载完成信号
    void maskUpdated(const cv::Mat &mask);      // 蒙版更新信号

protected:
    // 重写的Qt事件处理函数
    void paintEvent(QPaintEvent *event) override;       // 绘制事件
    void mousePressEvent(QMouseEvent *event) override;  // 鼠标按下
    void mouseMoveEvent(QMouseEvent *event) override;   // 鼠标移动
    void mouseReleaseEvent(QMouseEvent *event) override;// 鼠标释放

private:
    // ==================== 核心绘制函数 ====================
    void drawOnMask(const QPoint &pos);         // 在蒙版上绘制
    void updateScaledImages();                  // 更新缩放后的图像

    // ==================== 图像数据成员 ====================
    QPixmap originalPixmap;      // Qt格式的原始图像（用于显示）
    QPixmap displayPixmap;       // 缩放后的显示图像
    QPixmap maskPixmap;          // Qt格式的蒙版图像（用户绘制区域）

    cv::Mat originalImage;       // OpenCV格式的原始图像（用于算法处理）
    cv::Mat maskImage;           // OpenCV格式的蒙版（白色区域表示需要修复）

    // ==================== 状态控制成员 ====================
    double scaleFactor = 1.0;    // 当前缩放因子（1.0=原始大小）
    bool isDrawing = false;      // 正在绘制的标志
    Tool currentTool = Pen;      // 当前选中的工具
    int brushSize = 20;          // 画笔大小（像素）
    QPoint lastMousePos;         // 上一次鼠标位置（用于连续绘制）
};

#endif // IMAGECANVAS_H
